.\" Copyright (c) 2009, 2010, 2012 Kai Wang
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd March 6, 2010
.Dt UHIDD 8
.Os
.Sh NAME
.Nm uhidd
.Nd USB HID daemon
.Sh SYNOPSIS
.Nm
.Op Fl c Ar file
.Op Fl DdhkmosuVv
.Ar /dev/ugen%u.%u
.Sh DESCRIPTION
The
.Nm
daemon handles USB HID devices like mouse, keyboard etc. in userland using
the libusb20 library.
.Pp
The
.Nm
daemon is intended to handle USB HID devices with multiple logical
devices sharing one endpoint, usually that is multiple application
collections inside one interface. The daemon attaches interface driver
to each HID interface of the ugen%u.%u device and attaches class
drivers to application collections found inside that
inteface. Interface driver receive data through the shared interrupt
endpoint and pass it to the right class driver instance. The class
driver then process the data as approriate.
.Pp
There are currently 4 HID class driver available: Mouse driver,
Keyboard driver, Consumer Control driver and Virutal Generic HID
driver.
.Pp
The Mouse driver extracts mouse input data from mouse application
collection and pass the mouse event to the console driver to
make it available to the text console and user programs.
.Pp
The Keyboard
driver creates a
.Xr vkbd 4
virtual keyboard, extracts keyboard HID input report from keyboard
application collection, translates the HID codes to key scancodes
and passes the scancodes to the
.Xr vkbd 4
control device.
.Pp
The Consumer
Control class driver is basically a special keyboard driver that
handles multimedia keys found on USB keyboard. It translates
consumer page usage
.Pq USB multimedia keys
to unassigned or rarely used keycodes. See
.Xr uhidd.conf 5
for how to configure the keymap. If a multimedia keymap is not found
in the configuration for a USB keyboard, The driver
will create a in-memory keymap and assigns keycodes automatically
when multimedia keys are pressed. This in-memory keymap will also
be stored in
.Em /var/run/uhidd.ugen%u.%u/cc_keymap ,
and can be copy-pasted into configuration file so the driver can
load the keymap directly next time.
.Pp
All other HID application collections that don't
have a specific driver can be attached by the Virtual Generic HID
class driver. The driver creates a virtual USB HID device using
the
.Xr cuse4bsd 4
interface, so normal USB HID applications that deal with
.Xr uhid 4 ,
e.g.
.Xr usbhidctl 1 ,
could access the data through the virutal interface.
.Sh OPTIONS
The
.Nm
daemon supports the following options:
.Bl -tag -width indent-two
.It Fl c Ar file
Specify the path to the configuration file. The default path
is
.Em /usr/local/etc/uhidd.conf .
.It Fl D
Dump HID device report descriptor in human readable form.
This option implies
.Fl d .
.It Fl d
Do not detach from the controlling terminal, i.e., run in
foreground. This option is intended for debugging the daemon.
.It Fl h
Attach the Virtual Generic HID class driver.
This option requires that
.Xr cuse4bsd 4
driver loaded as a kernel module.
.It Fl H
Specify the name of the virtual HID device created by the
virtual generic HID driver. The default name used for the device is
.Dq uvhid .
.It Fl k
Attach Keyboard class driver. This option requires that
.Xr vkbd 4
compiled in the kernel or loaded as a kernel module,
and that the keyboard multiplexer
.Xr kbdmux 4
be enabled.
.It Fl m
Attach Mouse class driver.
.It Fl o
Attach Consumer Control class driver.
.It Fl s
Instruct the Virtual Generic HID driver to strip the report ID byte
from the hid report data. This is needed if the hid application is
using
.Xr usbhid 3
parser to parse the data read from the simulated
.Xr uhid 4
interface.
.It Fl u
When this option is specified, if there is an active kernel
driver attached to the device interface, the
.Nm uhidd
daemon will try to detach the active kernel driver first, before
attaching itself to the device.
This option is easpecially useful when there is no easy way to
unload the kernel USB HID device drivers.
If this option is not present and the
.Nm uhidd
daemon finds out the device is already attached by a kernel
driver, it will abort and let the kernel driver continue handling
the device.
.It Fl V
Output the version of
.Nm
daemon to stderr and exit.
.It Fl v
Output additional information for debugging purpose. Multiple
.Fl v
specified in the command line will increase the level of the
verbosity. This option implies
.Fl d .
.El
.Pp
There are more options that can be configured through
.Xr uhidd.conf 5 .
.Sh CAVEATS
The
.Nm uhidd
daemon can coexist with the kernel USB HID drivers for keyboard, mouse etc.
When the daemon starts, if it detects there is an active kernel driver
already attached to the device, it will abort gracefully. If the option
.Fl u
is specified or the configuration option
.Dq detach_kernel_driver
is applicable for the device, it will attempt to detach the kernel driver
first before attaching itself to the device.
.Pp
However note that if the kernel USB HID drivers are compiled as kernel
modules and are not yet loaded at the point when the device is attached
to the system, the
.Nm uhidd
daemon will attach itself to the device first, and the kernel driver will
be loaded and attached to the device after. As a result, both
.Nm uhidd
daemon and the kernel driver will attach to the device at the same time,
which causes undefined behaviours.
To overcome this problem, when the kernel drivers are compiled as modules,
the
.Xr devd 8
rules listed in the
.Dq /etc/devd/usb.conf
config file for the relevant USB HID kernel modules should be removed.
.Sh FILES
.Bl -tag -width /var/run/uhidd.ugen.%u.%u.pid/cc_keymap -compact
.It Pa /usr/local/etc/uhidd.conf
the default name of the configuration file
.It Pa /var/run/uhidd.ugen.%u.%u.pid
process id of the currently running
.Nm
daemon that attached to device ugen.%u.%u
.It Pa /var/run/uhidd.ugen.%u.%u/cc_keymap
the in-memory multimedia keymap for device ugen.%u.%u
.El
.Sh SEE ALSO
.Xr usbhidaction 1 ,
.Xr usbhidctl 1 ,
.Xr cuse4bsd 3 ,
.Xr usb 3 ,
.Xr usbhid 3 ,
.Xr uhid 4 ,
.Xr vkbd 4 ,
.Xr uhidd.conf 5 ,
.Xr bthidd 8 ,
.Xr moused 8
.Pp
There are additional instructions and setup examples in the web page:
.Em http://wiki.FreeBSD.org/uhidd
.Sh AUTHORS
The
.Nm
daemon was written by
.An Kai Wang Aq kaiw@FreeBSD.org ,
based on the work done by many others.
